home *** CD-ROM | disk | FTP | other *** search
/ United Public Domain Gold 2 / United Public Domain Gold 2.iso / utilities / pu314.dms / pu314.adf / NComm / Script.doc < prev    next >
Text File  |  1990-01-19  |  12KB  |  427 lines
  1. The NComm V1.8 scriptlanguage
  2. =============================
  3.  
  4. A scriptfile is an ASCII textfile that consists of different commands,
  5. separated by  one or more  linefeeds.  Edit the  scriptfiles with your
  6. favourite  editor.  Only  one  command is  allowed per line, but blank 
  7. lines are also OK. A line can consist of blanks before the command and
  8. between parameters.  Comments can be added by entering a semicolon.  A
  9. label is marked with a colon as its last character, e.g. "quit:".  The
  10. script  commands  are case independent,  but strings within quotes are 
  11. not. 
  12.  
  13. Scripts  are mainly used to automate logons, or to companion you while
  14. you  are  online.   Scripts  can also perform more advanced functions,
  15. like  grabbing  mail  and perhaps posting it on another board (or even
  16. printing it!).  You set the limits...
  17.  
  18. Two example scripts have been included with the NComm package.  Take a
  19. look at them if you don't understand how to use the commands.
  20.  
  21. Important:   The  filenames  specified in a scriptfile are relative to
  22. the   current   directory,   NOT   the  default  upload  and  download
  23. directories!
  24.  
  25.  
  26. Summary of Script commands
  27. --------------------------
  28.  
  29.         ASCSEND
  30. Starts ASCII text send of the filename given. Example:
  31.  
  32. ASCSEND "df1:text/msg"
  33.  
  34. ----------------------------------------------------------------------
  35.  
  36.         BEEP
  37. Will  cause  an audible 'beep' of the terminal and / or will flash the
  38. screen  and / or will bring the screen to front, depending on what you
  39. have configured in the SCREEN menu.  Nothing is sent through the serial
  40. port.
  41.  
  42. ----------------------------------------------------------------------
  43.  
  44.         BREAK
  45. Sends a break to the host machine. Equivalent to SEND "\l".
  46.  
  47. ----------------------------------------------------------------------
  48.  
  49.         CAPTURE
  50. Toggles ASCII capture on/off. Examples:
  51.  
  52. CAPTURE "filename"
  53. Will  open the capture file and turn on capture.  It will be opened in
  54. 'append mode' if the file exists...
  55.  
  56. CAPTURE SUS
  57. Will suspend capture.  Capture can be turned on again with the command
  58. CAPTURE ON
  59.  
  60. CAPTURE OFF
  61. Will  turn  capture off and close the file.  The file cannot be opened
  62. again with the CAPTURE ON command.
  63.  
  64. ----------------------------------------------------------------------
  65.  
  66.         CD
  67. Problems  occur  when  the "CD" command is used with the CLI function.
  68. The  "CD"  command  has  therefore  been  made a special function.  It
  69. simply  changes  the directory that is to be used for commands started
  70. with the "CLI" function.
  71.  
  72. Example:
  73.  
  74. CD "RAM:"       ;Will change the current working directory to 'RAM:'
  75.  
  76. ----------------------------------------------------------------------
  77.  
  78.         CHAIN
  79. Will start a new script.  The control will never return to the calling
  80. script.   This  is  useful  when  you need extremely long scripts that
  81. won't fit in memory.
  82.  
  83. Example:
  84.  
  85. CHAIN "NComm:ReadNews.script"
  86.  
  87. ----------------------------------------------------------------------
  88.  
  89.         CLI
  90. Will  execute  a program or a command.  The output from these programs
  91. and  commands  will  occur  in the NComm window.  This command will be
  92. relative to the directory you were standing in when you started NComm.
  93.  
  94. Please  note;  Current  Directory can not be set with the CLI command,
  95. probably  due  to  problems with the Amiga operating system.  The "CD"
  96. function must therefore be used for this purpose.
  97.  
  98. Examples:
  99.  
  100. CLI "dir dh0:comms"
  101. CLI "type ram:foo.bar"
  102. CLI "pkax ram:grabfile.arc"
  103.  
  104. ----------------------------------------------------------------------
  105.  
  106.         CONFIG
  107. Will read a new configuration file.  Example:
  108.  
  109. CONFIG "NComm:MBBS.config"
  110.  
  111. ----------------------------------------------------------------------
  112.  
  113.         CONVERSE
  114. Will wait for a prompt from the host machine and answer it.
  115.  
  116. Examples:
  117.  
  118. CONVERSE "Enter your name:" "Name\n"   ;Waits for 'Enter your name:'
  119. CONVERSE "enter your password:" "\p\n" ;Sends phonebook password + CR
  120. CONVERSE "Command:" "G\n"              ;Sends 'G' and newline
  121.  
  122. ----------------------------------------------------------------------
  123.  
  124.         DELAY
  125. The  script  program  will take a break.  The program will function as
  126. normal.
  127.  
  128. Examples:
  129.  
  130. DELAY 5                 ;Wait 5 seconds
  131. DELAY UNTIL 12:00       ;Wait until 12 o'clock.
  132.  
  133. ----------------------------------------------------------------------
  134.  
  135.         DIAL
  136. Will  dial  one  or  more  phonenumbers.  Can also dial entries in the
  137. phonebook.   If  you  choose  to  dial  phonenumbers,  use the command
  138. 'DIAL#'.   The  numbers must be placed within quotation marks.  If you
  139. choose to dial more than one number, the numbers can be separated by a
  140. comma.
  141.  
  142. Examples:
  143.  
  144. DIAL# "454143"
  145. DIAL# "380949", "493210", "454143"
  146.  
  147. Named  entries  in  the  phonebook  can  be  dialled by specifying the
  148. boardname within quotation marks.  You only have to specify the number
  149. of  letters  required  to  separate  the  board  from the others.  The
  150. name is not case sensitive.
  151.  
  152. Examples:
  153.  
  154. DIAL "AmigaBBS"
  155. DIAL "rode", "Mike's", "media"
  156. DIAL "Rodeløkka (M)BBS"
  157.  
  158. ----------------------------------------------------------------------
  159.  
  160.         DOWNLOAD
  161. Will download a file from the host machine.  The protocol specified in
  162. the  TRANSFER  menu will be used as long as nothing else is specified.
  163. If you want to specify another protocol, enter a comma and a letter.
  164.  
  165. X == Xmodem, Y == Ymodem.
  166.  
  167. Examples:
  168.  
  169. DOWNLOAD "df1:junk"             ;Will use the default protocol
  170. DOWNLOAD "df0:trash",X          ;Will always use Xmodem
  171.  
  172. ----------------------------------------------------------------------
  173.  
  174.         DTENTHS
  175. This  is  a much more precise delay command, but only use this command
  176. when  this  accuracy is needed, since it will lock up the system.  The
  177. DTENTHS parameter is the number of tenth seconds to wait.
  178.  
  179. Examples:
  180.  
  181. DTENTHS 2       ;Wait 0.2 seconds
  182. DTENTHS 16      ;Wait 1.6 seconds
  183.  
  184. ----------------------------------------------------------------------
  185.  
  186.         DWHENS
  187. Will disable all previously used WHEN commands. See: WHEN.
  188.  
  189. ----------------------------------------------------------------------
  190.  
  191.         END
  192. Will  stop  the  execution  of the script.  This command is especially
  193. useful in front of subroutines.
  194.  
  195. Example:
  196.  
  197. WHEN "Read>" GOSUB next
  198. WAIT "No more unread."
  199. END
  200.  
  201. Next: SEND "\n"
  202.       MESSAGE "(Skipping to next unread)\n"
  203.       RETURN
  204.  
  205. ----------------------------------------------------------------------
  206.  
  207.         GOSUB
  208. Will  call  a  named subroutine.  Useful when you want to use the same
  209. command  many  times  within  a  script, or in connection with WHEN or
  210. TIMEOUT.   The  subroutine  is ended with 'RETURN', and the control is
  211. passed to the line following the GOSUB afterwards.
  212.  
  213. Example:
  214.  
  215. GOSUB myRoutine
  216. END
  217.  
  218. MyRoutine: MESSAGE "Fooo\n"
  219.            BEEP
  220.            RETURN
  221.  
  222. ----------------------------------------------------------------------
  223.  
  224.         GOTO
  225. Ever heard of this? Will jump to a named place in the script.
  226.  
  227. Example:
  228.  
  229. GOTO quit
  230. ...
  231. quit: CAPTURE OFF
  232.       HANGUP
  233.       END
  234.  
  235. ----------------------------------------------------------------------
  236.  
  237.         HANGUP
  238. Will send the hangup string to the modem.
  239.  
  240. ----------------------------------------------------------------------
  241.  
  242.         LOADKEYS
  243. Will read a new macrokeys file.
  244.  
  245. Example:
  246.  
  247. LOADKEYS "NComm:dec.Keys"
  248.  
  249. ----------------------------------------------------------------------
  250.  
  251.         LOADPHONE
  252. Will read a new phonebook file.
  253.  
  254. Example:
  255.  
  256. LOADPHONE "NComm:dialdir.phone"
  257.  
  258. ----------------------------------------------------------------------
  259.  
  260.         MESSAGE
  261. Will write a message on the screen.  Nothing is sent through the serial
  262. port.
  263.  
  264. Example:
  265.  
  266. MESSAGE "\fReading mail...\n"
  267. MESSAGE "Storing mail in file \"DF1:Mail.txt\"\n"
  268.  
  269. ----------------------------------------------------------------------
  270.  
  271.         MSGSEND
  272. Same  as the "message send" function in the TRANSFER menu, will upload
  273. a message.
  274.  
  275. Example:
  276.  
  277. MSGSEND "DF1:tekst/msg"
  278.  
  279. ----------------------------------------------------------------------
  280.  
  281.         PRINTER
  282. Turns the printer ON or OFF.
  283.  
  284. Example:
  285.  
  286. PRINTER ON      ;Will turn on the printer
  287. PRINTER OFF     ;Will turn off the printer
  288.  
  289. ----------------------------------------------------------------------
  290.  
  291.         QUIT
  292. Exits NComm.
  293.  
  294. ----------------------------------------------------------------------
  295.  
  296.         REQUEST
  297. This  function  is  used  when  the  scriptfile  is  run without human
  298. presence.   It  will  then  be  unpreferable  that  AmigaDOS puts up a
  299. requester  if  problems  occur (disk full, read / write error etc.) By
  300. turning request OFF, this is disabled.
  301.  
  302. Example:
  303.  
  304. REQUEST OFF     ;Turns requesters off
  305. REQUEST ON      ;Will turn the requesters back on again
  306.  
  307. ----------------------------------------------------------------------
  308.  
  309.         RETURN
  310. Returns from a subroutine. See GOSUB.
  311.  
  312. ----------------------------------------------------------------------
  313.  
  314.         SEND
  315. Sends a string to the host machine.
  316.  
  317. Examples:
  318.  
  319. SEND "\n"       ;Linefeed
  320. SEND "Read\n"   ;'Read' plus a CR
  321. SEND "\m1^z"    ;Macro #1 plus a 'Control-Z'
  322. SEND "\p\n"     ;The password stored in the phonebook plus a CR
  323.  
  324. ----------------------------------------------------------------------
  325.  
  326.         TIMEOUT
  327. This  command  lets you configure how long NComm should wait in a WAIT
  328. or  CONVERSE  command.   Default timeout is 'forever', but this is not
  329. preferable  if the script is running without human assistance.  If the
  330. host  machine does not answer, it is reasonable to believe that it has
  331. hung,  and  a scriptfile should then automatically disconnect from the
  332. system.  The TIMEOUT command can be used in many ways.
  333.  
  334. Examples:
  335.  
  336. TIMEOUT 10
  337. Means  that  NComm shall wait a maximum of 10 seconds.  If no text has
  338. been  received  within  the  timelimit, NComm will go on with the next
  339. command.
  340.  
  341. TIMEOUT 10 SEND "\n"
  342. Specifies  that NComm is to wait a maximum of 10 seconds for each WAIT
  343. or  CONVERSE  command.   If  the  specified text has not been received
  344. within  10 seconds, NComm will send a linefeed to the host machine and
  345. will  continue  waiting  for  the  text.   NComm will continue sending
  346. linefeeds every 10th second until the host machine has answered.
  347.  
  348. TIMEOUT 0
  349. NComm is to go back to the default mode, i.e. wait forever.
  350.  
  351. Example of typical usage:
  352.  
  353. TIMEOUT 30 GOTO quit
  354. CONVERSE "Enter your name:" "Daniel Bloch\n"
  355. CONVERSE "Enter your password:" "gruff\n"
  356. CONVERSE "Command:" "GRAB\n"
  357. ...
  358. ...
  359. END
  360.  
  361. quit: MESSAGE "\n\nThe board has hung, call the SysOp!!!\n"
  362.       BEEP
  363.       HANGUP ;Hang up so that we won't get a shock when
  364.       END    ;the next phonebill arrives!
  365.  
  366. ----------------------------------------------------------------------
  367.  
  368.         UPLOAD
  369. Uploads  a  file to the host machine.  See the 'DOWNLOAD' function for
  370. the correct syntax.
  371.  
  372. ----------------------------------------------------------------------
  373.  
  374.         WAIT
  375. Waits  for  a  special  text to be received.  Will wait forever if the
  376. TIMEOUT command has not been used.
  377.  
  378. Examples:
  379.  
  380. WAIT "Command:" ;Wait for 'Command:'
  381. WAIT "\n"       ;Wait for a linefeed
  382. WAIT ""         ;Wait for 'anything'
  383.  
  384. ----------------------------------------------------------------------
  385.  
  386.         WHEN
  387. Defines what to do when a special text is received.
  388.  
  389. Typical example:
  390.  
  391. WHEN "--more--" SEND " "
  392.  
  393. This  command  will  make  NComm  send  a  'blank'  line every time it
  394. receives the 'more' prompt from the host machine.  This is independent
  395. of  where  in the script  you reside.  It is possible to specify up to
  396. ten such textstrings.
  397.  
  398. Example:
  399.  
  400. WHEN "--more--" SEND " "
  401. WHEN "NO CARRIER" END
  402. WHEN "Sysop is coming online!" GOSUB ShutUp
  403. WHEN "No more unread" GOTO quit
  404.  
  405. loop: CONVERSE "Command:" "\n"
  406.       GOTO loop
  407.  
  408. quit: SEND "G;Y\n"
  409.       END
  410.  
  411. ShutUp: SEND "I'm not at home! You are chatting with a scriptfile!\n"
  412.         SEND "Send BIBI at the speed of light!!!\n\n"
  413.         RETURN
  414.  
  415. Input from the keyboard is echoed back from the modem when off-line,
  416. which makes it possible to request input from the user before dialling:
  417.  
  418. MESSAGE "Execute MBBS.script (y/n) ?"
  419. WHEN "Y" goto yes
  420. WAIT "N"
  421. END
  422.  
  423. yes: DWHENS
  424.      ...
  425.  
  426.  
  427.